home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1994…tember: Reference Library / Dev.CD Sep 94.toast / Periodicals / develop / develop Issue 18 / develop 18 code / Preferences Files / Library ƒ / StdPrefsLib.h < prev    next >
Encoding:
Text File  |  1994-03-17  |  12.0 KB  |  300 lines  |  [TEXT/KAHL]
  1. /*
  2.     File:        StdPrefsLib.h
  3.  
  4.     Contains:    Header file for standard preferences library routines.
  5.  
  6.                 Refer to develop Issue 18, "The Right Way to Implement 
  7.                 Preferences Files", for additional details on this code.
  8.                 
  9.     Written by:    Gary Woodcock
  10.  
  11.     Copyright:    © 1993-94 by Apple Computer, Inc.
  12.     Change History (most recent first):
  13.     
  14.                   3/3/94    Version 1.0.
  15.     
  16.     Notes:         This code uses Apple's Universal Interfaces for C.
  17.     
  18.                 Send bug reports to Gary Woodcock at AOL: gwoodcock
  19.                 or Internet: gwoodcock@aol.com.
  20. */
  21.  
  22. //-----------------------------------------------------------------------
  23. // Includes
  24.  
  25. #ifndef    _STDPREFSLIB_
  26. #define    _STDPREFSLIB_
  27.  
  28. #include "CompileFlags.h"
  29.  
  30. #ifndef forRez
  31.  
  32. #include <Files.h>
  33.  
  34. #endif forRez
  35.  
  36. //-----------------------------------------------------------------------
  37. // Public constants
  38.  
  39. #ifndef forRez
  40.  
  41. // Valid version resource ('vers') ID's
  42. enum
  43. {
  44.     kVers1 = 1,
  45.     kVers2
  46. };
  47.  
  48. //-----------------------------------------------------------------------
  49. // Public interfaces
  50.  
  51. #ifdef __cplusplus
  52. extern "C" {
  53. #endif __cplusplus
  54.  
  55. //-----------------------------------------------------------------------
  56. // NewPreferencesFile creates a new preferences file with the specified
  57. // creator, file type and name in the System Folder (prior to System 7)
  58. // or the Preferences folder (System 7 or later). File names with zero-length
  59. // strings are not permitted. You can optionally specify a custom 
  60. // preferences folder of your own with the folderName argument; pass nil
  61. // for this argument if you don't want to use a custom preferences
  62. // folder. If a folder name that is not a zero-length string is provided, 
  63. // NewPreferencesFile checks to see if the folder exists; if it doesn't, 
  64. // NewPreferencesFile creates the folder. Another option is to provide
  65. // the name of the program (application, extension, etc.) in the ownerName
  66. // argument; if this argument is supplied, a custom application-missing
  67. // message string resource is created for the preferences file.
  68. //
  69. // Errors:
  70. //
  71. //      paramErr    - The fileName or ownerName argument is a zero-length 
  72. //                    string.
  73. //      dupFNErr    - A preferences file with this name, creator and file
  74. //                  type already exists.
  75. //
  76. //      Other ResError() or file system codes can be returned, but 
  77. //      this should not normally occur.
  78. //-----------------------------------------------------------------------
  79. pascal OSErr
  80. NewPreferencesFile (OSType creator, OSType fileType, 
  81.     ConstStr31Param fileName, ConstStr31Param folderName, 
  82.     ConstStr31Param ownerName);
  83.     
  84. //-----------------------------------------------------------------------
  85. // OpenPreferencesFile opens the preferences file with the specified
  86. // creator and file type.  You must have created the file with the 
  87. // NewPreferencesFile call before making this call. 
  88. //
  89. // Errors:
  90. //
  91. //      paramErr    - The fRefNum argument is nil.
  92. //    fnfErr      - There is no preferences file with the specified
  93. //                  creator and file type; use NewPreferencesFile to 
  94. //                    create one.
  95. //
  96. //      Other ResError() or file system codes can be returned, but 
  97. //      this should not normally occur.
  98. //-----------------------------------------------------------------------
  99. pascal OSErr
  100. OpenPreferencesFile (OSType creator, OSType fileType, short *fRefNum);
  101.     
  102. //-----------------------------------------------------------------------
  103. // ClosePreferencesFile closes the currently open preferences file
  104. // for this instance of the standard preferences component.  If there is
  105. // no preferences file currently open, an error is returned.
  106. //
  107. // Errors:
  108. //
  109. //      paramErr    - Bad file reference in fRefNum argument.
  110. //
  111. //      Other ResError() codes can be returned, but this should not 
  112. //    normally occur.
  113. //-----------------------------------------------------------------------
  114. pascal OSErr
  115. ClosePreferencesFile (short fRefNum);
  116.     
  117. //-----------------------------------------------------------------------
  118. // DeletePreferencesFile deletes the preferences file with the specified
  119. // creator and file type.  If the preferences file is open, an error is 
  120. // returned; you must make sure any preferences files are closed before 
  121. // attempting to delete them. 
  122. //
  123. // Errors:
  124. //
  125. //      fBsyErr     - The specified preferences file is currently open, 
  126. //                    and must be closed before it can be deleted.
  127. //      fnfErr      - A preferences file with the specified creator and
  128. //                    file type could not be found.
  129. //
  130. //      Other file system codes can be returned, but this should not 
  131. //    normally occur.
  132. //-----------------------------------------------------------------------
  133. pascal OSErr
  134. DeletePreferencesFile (OSType creator, OSType fileType);
  135.  
  136. //-----------------------------------------------------------------------
  137. // DeletePreferencesFolder deletes the preferences folder specified by the
  138. // folderName argument. An attempt will be made to locate the specified
  139. // folder by first searching the Preferences folder and its nested folders
  140. // (if the Preferences folder exists), then by searching the System Folder.
  141. //
  142. // Errors:
  143. //
  144. //    paramErr    - The folderName argument is a zero-length string.
  145. //      dirNFErr      - A folder with the specified name could not be
  146. //                    found.
  147. //
  148. //      Other file system codes can be returned, but this should not 
  149. //    normally occur.
  150. //-----------------------------------------------------------------------
  151. pascal OSErr
  152. DeletePreferencesFolder (ConstStr31Param folderName);
  153.     
  154. //-----------------------------------------------------------------------
  155. // PreferencesFileExists determines whether a preferences file already
  156. // exists or not. If the file specified by the creator and file type 
  157. // exists in either the Preferences folder (anywhere) or in the System 
  158. // Folder, true is returned; if it doesn't exist, false is returned.
  159. //
  160. // Errors:
  161. //
  162. //      None.
  163. //-----------------------------------------------------------------------
  164. pascal Boolean
  165. PreferencesFileExists (OSType creator, OSType fileType);
  166.     
  167. //-----------------------------------------------------------------------
  168. // GetPreferencesFileVersion returns the contents of the specified 'vers'
  169. // resource of the currently open preferences file.  You can use this 
  170. // information to distinguish between current and older versions of your 
  171. // preferences files (say, between the preferences files for version 1.5 
  172. // and 1.0 of your application program).  You must have called 
  173. // OpenPreferencesFile previously before making this call.  Only versID's 
  174. // with a value of kVers1 or kVers2 are allowed.
  175. //
  176. // Errors:
  177. //
  178. //      paramErr    - A value other than kVers1 or kVers2 was passed for the 
  179. //                    versID argument, a bad address was passed for the 
  180. //                    numVersion argument or the regionCode argument, or the
  181. //                    fRefNum argument contains a bad file reference.
  182. //        
  183. //      Other file system, ResError(), or MemError() codes can be returned,
  184. //    but this should not normally occur.
  185. //-----------------------------------------------------------------------
  186. pascal OSErr
  187. GetPreferencesFileVersion (short fRefNum, short versID, 
  188.     NumVersion *numVersion, short *regionCode, 
  189.     ConstStr255Param shortVersionStr, ConstStr255Param longVersionStr);
  190.     
  191. //-----------------------------------------------------------------------
  192. // SetPreferencesFileVersion lets you set the contents of the specified 
  193. // 'vers' resource of the currently open preferences file.  You must have 
  194. // called OpenPreferencesFile previously before making this call.  Only 
  195. // versID's with a value of kVers1 or kVers2 are allowed.
  196. //
  197. // Errors:
  198. //
  199. //      paramErr    - A value other than kVers1 or kVers2 was passed for 
  200. //                    the versID argument, a bad address was passed for 
  201. //                    the numVersion argument, or the fRefNum argument
  202. //                    contains a bad file reference.
  203. //
  204. //      Other file system, ResError(), or MemError() codes can be returned,
  205. //    but this should not normally occur.
  206. //-----------------------------------------------------------------------
  207. pascal OSErr
  208. SetPreferencesFileVersion (short fRefNum, short versID, 
  209.     NumVersion *numVersion, short regionCode, 
  210.     ConstStr255Param shortVersionStr, ConstStr255Param longVersionStr);
  211.      
  212. //-----------------------------------------------------------------------
  213. // ReadPreference reads the specified preference resource from the 
  214. // currently open preferences file.  If you pass in nil for the address 
  215. // of the resourceID argument, or if you pass in 0 for the value of the 
  216. // resource ID, then ReadPreferences will find the first resource with 
  217. // the specified type in the currently open preferences file.  If you pass 
  218. // in 0 for the value of the resource ID, then OpenPreferencesFile will 
  219. // return the resourceID corresponding to the preference resource it found.  
  220. // You must have called OpenPreferencesFile previously before making this 
  221. // call.
  222. //
  223. // Errors:
  224. //
  225. //      paramErr    - The address of the preference argument is nil, or 
  226. //                    the fRefNum argument contains a bad file reference.
  227. //      resNotFound - No resource with the specified type and/or ID was
  228. //                  found.
  229. //
  230. //    Other ResError() codes can be returned, but this should not 
  231. //    normally occur.
  232. //-----------------------------------------------------------------------
  233. pascal OSErr
  234. ReadPreference (short fRefNum, ResType resourceType, short *resourceID, 
  235.     Handle *preference);
  236.     
  237. //-----------------------------------------------------------------------
  238. // WritePreference writes the specified preference resource to the 
  239. // currently open preferences file.  If you pass in nil for the address 
  240. // of the resourceID argument, or if you pass in 0 for the value of the 
  241. // resource ID, then WritePreferences assigns the preference resource a 
  242. // resource ID and returns it in the resourceID argument (if its address 
  243. // isn't nil).  If a resource with the same type and ID already exists 
  244. // in the preferences file, the existing resource is replaced with the 
  245. // new one.  You must have called OpenPreferencesFile previously before 
  246. // making this call.  WritePreference checks to make sure that there is a 
  247. // minimum amount of disk space left before actually writing out the 
  248. // preference to the preferences file - if there isn't enough disk space, 
  249. // the preferences file will be untouched, and an error will be returned.
  250. // The actual size of this minimum amount is dependent on the allocation
  251. // block size of the volume that the preferences file is located on.  
  252. // IMPORTANT NOTE:  It is the caller's responsibility to dispose the 
  253. // memory occupied by the preference argument - WritePreference does NOT 
  254. // dispose this memory.
  255. //
  256. // Errors:
  257. //
  258. //      paramErr       - The preference argument is nil, or the fRefNum argument
  259. //                    contains a bad file reference.
  260. //    dskFulErr   - The preference can't be written and still maintain a 
  261. //                  minimum amount of free space on the disk.
  262. //
  263. //      Other MemError() or ResError() codes can be returned, but this should
  264. //    not normally occur.
  265. //-----------------------------------------------------------------------
  266. pascal OSErr
  267. WritePreference (short fRefNum, ResType resourceType, short *resourceID, 
  268.     Handle preference);
  269.     
  270. //-----------------------------------------------------------------------
  271. // DeletePreference deletes the specified preference resource from the 
  272. // currently open preferences file.  If you pass in 0 for the resourceID 
  273. // argument, then DeletePreference will delete the first resource of the 
  274. // specified type in the currently open preferences file.  You must have 
  275. // called OpenPreferenceFile previously before making this call.
  276. //
  277. // Errors:
  278. //
  279. //      paramErr    - The fRefNum argument contains a bad file reference.
  280. //      resNotFound - No resource with the specified type and/or ID was
  281. //                  found.
  282. //
  283. //      Other MemError() or ResError() codes can be returned, but this 
  284. //    should not normally occur.
  285. //-----------------------------------------------------------------------
  286. pascal OSErr
  287. DeletePreference (short fRefNum, ResType resourceType, short resourceID);
  288.     
  289. #ifdef __cplusplus
  290. }
  291. #endif __cplusplus
  292.  
  293. #endif forRez
  294.  
  295. //-----------------------------------------------------------------------
  296.  
  297. #endif _STDPREFSLIB_
  298.  
  299. //-----------------------------------------------------------------------
  300.